/*!
 * \file UftStrategyDefs.h
 * \project	WonderTrader
 *
 * \author Wesley
 * \date 2020/03/30
 * 
 * \brief UFT策略定义文件
 * \details 定义了UFT(Ultra Fast Trading)策略的基础类和策略工厂接口，提供超高频交易策略开发的核心框架
 */
#pragma once
#include <string>
#include <stdint.h>

#include "../Includes/WTSMarcos.h"

NS_WTP_BEGIN
class WTSVariant;
class IUftStraCtx;
class WTSTickData;
class WTSOrdDtlData;
class WTSOrdQueData;
class WTSTransData;
struct WTSBarStruct;
NS_WTP_END

USING_NS_WTP;

/**
 * @class UftStrategy
 * @brief UFT策略基类
 * @details UFT(Ultra Fast Trading)策略的基础类，提供超高频交易策略开发的基本框架。
 *          主要功能包括：
 *          - 策略生命周期管理
 *          - 微秒级市场数据处理
 *          - Level2深度数据实时分析
 *          - 超低延迟交易执行
 *          - 精确持仓管理
 *          - 高性能订单管理
 *          
 *          UFT策略主要用于微秒级的超高频交易，通常基于市场微结构、
 *          套利机会、流动性提供等进行极短时间内的交易决策。
 *          策略对延迟极其敏感，需要特别优化性能和网络传输。
 */
class UftStrategy
{
public:
	/**
	 * @brief 构造函数
	 * @param id 策略实例ID
	 */
	UftStrategy(const char* id) :_id(id){}
	virtual ~UftStrategy(){}

public:
	/**
	 * @brief 获取策略名称
	 * @details 返回策略的唯一标识名称，用于策略识别和管理。
	 * @return const char* 策略名称
	 */
	virtual const char* getName() = 0;

	/**
	 * @brief 获取策略工厂名称
	 * @details 返回创建此策略的工厂名称，用于策略来源追踪。
	 * @return const char* 策略工厂名称
	 */
	virtual const char* getFactName() = 0;

	/**
	 * @brief 策略初始化
	 * @details 策略启动时的初始化方法，用于加载配置和设置初始状态。
	 * @param cfg 配置参数对象
	 * @return bool true表示初始化成功，false表示失败
	 */
	virtual bool init(WTSVariant* cfg){ return true; }

	/**
	 * @brief 获取策略实例ID
	 * @return const char* 策略实例ID
	 */
	virtual const char* id() const { return _id.c_str(); }

	/**
	 * @brief 策略初始化回调
	 * @details 策略框架初始化完成后的回调函数，必须实现此方法进行策略特定的初始化操作。
	 *          这个回调在整个生命周期中只会调用一次。
	 * @param ctx UFT策略上下文指针
	 */
	virtual void on_init(IUftStraCtx* ctx) = 0;

	/**
	 * @brief 交易会话开始回调
	 * @details 每个交易日会话开始时的回调函数。
	 *          实盘时，除了每日第一次会话会调用on_init方法外，其他会话只会调用这个方法。
	 *          回测时，会话开始会调用此方法多次。
	 *          如果有一些需要每次会话开始都要处理的逻辑，可以放在这个回调里处理，
	 *          这样实盘就和回测保持一致了。
	 * @param ctx UFT策略上下文指针
	 * @param uTDate 交易日期，格式为yyyyMMdd
	 */
	virtual void on_session_begin(IUftStraCtx* ctx, uint32_t uTDate) {}

	/**
	 * @brief 交易会话结束回调
	 * @details 每个交易日会话结束时的回调函数。
	 * @param ctx UFT策略上下文指针
	 * @param uTDate 交易日期，格式为yyyyMMdd
	 */
	virtual void on_session_end(IUftStraCtx* ctx, uint32_t uTDate) {}

	/**
	 * @brief Tick数据回调
	 * @details 实时tick数据到达时的回调函数，用于处理最新的价格和成交信息。
	 * @param ctx UFT策略上下文指针
	 * @param stdCode 标准合约代码
	 * @param newTick 新的tick数据
	 */
	virtual void on_tick(IUftStraCtx* ctx, const char* stdCode, WTSTickData* newTick) {}

	/**
	 * @brief 委托队列数据回调
	 * @details Level2委托队列数据更新时的回调函数，提供买卖队列的详细信息。
	 * @param ctx UFT策略上下文指针
	 * @param stdCode 标准合约代码
	 * @param newOrdQue 新的委托队列数据
	 */
	virtual void on_order_queue(IUftStraCtx* ctx, const char* stdCode, WTSOrdQueData* newOrdQue) {}

	/**
	 * @brief 逐笔委托数据回调
	 * @details Level2逐笔委托数据更新时的回调函数，提供每笔委托的详细信息。
	 * @param ctx UFT策略上下文指针
	 * @param stdCode 标准合约代码
	 * @param newOrdDtl 新的逐笔委托数据
	 */
	virtual void on_order_detail (IUftStraCtx* ctx, const char* stdCode, WTSOrdDtlData* newOrdDtl) {}

	/**
	 * @brief 逐笔成交数据回调
	 * @details Level2逐笔成交数据更新时的回调函数，提供每笔成交的详细信息。
	 * @param ctx UFT策略上下文指针
	 * @param stdCode 标准合约代码
	 * @param newTrans 新的逐笔成交数据
	 */
	virtual void on_transaction(IUftStraCtx* ctx, const char* stdCode, WTSTransData* newTrans) {}

	/**
	 * @brief K线闭合回调
	 * @details K线数据更新时的回调函数，可以在此进行基于K线的策略逻辑。
	 * @param ctx UFT策略上下文指针
	 * @param stdCode 标准合约代码，格式如SHFE.rb2205
	 * @param period K线周期
	 * @param times 周期倍数
	 * @param newBar 新的K线数据
	 */
	virtual void on_bar(IUftStraCtx* ctx, const char* stdCode, const char* period, uint32_t times, WTSBarStruct* newBar) {}

	/**
	 * @brief 成交回报回调
	 * @details 策略订单成交时的回调函数，用于处理成交确认信息。
	 * @param ctx UFT策略上下文指针
	 * @param localid 本地订单ID
	 * @param stdCode 标准合约代码，格式如SHFE.rb2205
	 * @param isLong 是否为多头订单
	 * @param offset 开平标志：0-开仓，1-平仓，2-平今
	 * @param vol 成交数量
	 * @param price 成交价格
	 */
	virtual void on_trade(IUftStraCtx* ctx, uint32_t localid, const char* stdCode, bool isLong, uint32_t offset, double vol, double price) {}

	/**
	 * @brief 持仓同步回调
	 * @details 当通道连接成功时，会查询到持仓，触发这个回调。
	 *          如果没有查询到，则不会触发，所以这个接口不适合放任何状态相关的动作。
	 * @param ctx UFT策略上下文指针
	 * @param stdCode 标准合约代码，格式如SHFE.rb2205
	 * @param isLong 是否为多头持仓
	 * @param prevol 原有总持仓
	 * @param preavail 原有可用持仓
	 * @param newvol 最新总持仓
	 * @param newavail 最新可用持仓
	 */
	virtual void on_position(IUftStraCtx* ctx, const char* stdCode, bool isLong, double prevol, double preavail, double newvol, double newavail) {}

	/**
	 * @brief 订单回报回调
	 * @details 策略订单状态发生变化时的回调函数，用于监控订单执行状态。
	 * @param ctx UFT策略上下文指针
	 * @param localid 本地订单ID
	 * @param stdCode 标准合约代码，格式如SHFE.rb2205
	 * @param isLong 是否为多头订单
	 * @param offset 开平标志：0-开仓，1-平仓，2-平今
	 * @param totalQty 订单总数量
	 * @param leftQty 剩余未成交数量
	 * @param price 委托价格
	 * @param isCanceled 是否已撤销
	 */
	virtual void on_order(IUftStraCtx* ctx, uint32_t localid, const char* stdCode, bool isLong, uint32_t offset, double totalQty, double leftQty, double price, bool isCanceled) {}

	/**
	 * @brief 交易通道就绪回调
	 * @details 交易通道连接成功并准备就绪时的回调函数。
	 * @param ctx UFT策略上下文指针
	 */
	virtual void on_channel_ready(IUftStraCtx* ctx) {}

	/**
	 * @brief 交易通道断开回调
	 * @details 交易通道连接断开时的回调函数，需要处理断线重连逻辑。
	 * @param ctx UFT策略上下文指针
	 */
	virtual void on_channel_lost(IUftStraCtx* ctx) {}

	/**
	 * @brief 下单回报回调
	 * @details 订单下单确认时的回调函数。
	 *          有些接口只有下单优化的话会有这个回报，可以通过这个接口作为下单是否成功的回报。
	 * @param localid 本地订单ID
	 * @param bSuccess 是否成功
	 * @param message 错误信息
	 */
	virtual void on_entrust(uint32_t localid, bool bSuccess, const char* message) {}

protected:
	std::string _id;	///< 策略实例ID
};

//////////////////////////////////////////////////////////////////////////
/// @brief UFT策略枚举回调函数类型
/// @param factName 工厂名称
/// @param straName 策略名称
/// @param isLast 是否为最后一个策略
typedef void(*FuncEnumUftStrategyCallback)(const char* factName, const char* straName, bool isLast);

/**
 * @class IUftStrategyFact
 * @brief UFT策略工厂接口
 * @details UFT策略工厂的核心接口，负责超高频交易策略的创建、删除和管理。
 *          主要功能包括：
 *          - 策略实例创建和销毁
 *          - 策略类型枚举
 *          - 工厂标识管理
 *          
 *          策略工厂采用工厂模式设计，支持动态加载和卸载策略模块，
 *          为超高频交易策略系统提供灵活的扩展机制。特别适用于需要
 *          极低延迟和高性能的交易环境。
 */
class IUftStrategyFact
{
public:
	IUftStrategyFact(){}
	virtual ~IUftStrategyFact(){}

public:
	/**
	 * @brief 获取工厂名称
	 * @details 返回策略工厂的唯一标识名称。
	 * @return const char* 工厂名称
	 */
	virtual const char* getName() = 0;

	/**
	 * @brief 枚举策略
	 * @details 枚举工厂支持的所有策略类型，通过回调函数返回策略信息。
	 * @param cb 枚举回调函数，用于接收策略信息
	 */
	virtual void enumStrategy(FuncEnumUftStrategyCallback cb) = 0;

	/**
	 * @brief 根据策略名称创建策略实例
	 * @details 根据指定的策略名称和实例ID创建新的UFT策略实例。
	 * @param name 策略名称
	 * @param id 策略实例ID
	 * @return UftStrategy* 策略实例指针，创建失败返回nullptr
	 */
	virtual UftStrategy* createStrategy(const char* name, const char* id) = 0;

	/**
	 * @brief 删除策略实例
	 * @details 销毁指定的策略实例并释放相关资源。
	 * @param stra 要删除的策略实例指针
	 * @return bool true表示删除成功，false表示失败
	 */
	virtual bool deleteStrategy(UftStrategy* stra) = 0;
};

/// @brief 创建UFT策略工厂函数指针类型
typedef IUftStrategyFact* (*FuncCreateUftStraFact)();

/// @brief 删除UFT策略工厂函数指针类型
typedef void(*FuncDeleteUftStraFact)(IUftStrategyFact* &fact);
